home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / pars7.exe / PARS7.DOC < prev    next >
Encoding:
Text File  |  1993-05-12  |  10.1 KB  |  252 lines
  1.                              PARS7
  2.                             -------
  3. Author:
  4. Renate Schaaf
  5. 1253N 400E #3
  6. Logan, UT 84321
  7. CompuServe: 71031,2774
  8. E-mail: schaaf@math.usu.edu
  9.  
  10. Contents of the package:
  11. Pars7.doc    (This file)
  12. Pars7.pas    (Unit to translate a string given to a program at run time
  13.                into a tree of operations in memory which subsequently can
  14.                be called as a function, or rather a procedure that returns
  15.                a variable evaluating the string, that's a little faster.)
  16. Builder.pas   (Unit used by Pars7 to build the function.)
  17. Pars7Glb.pas  (Unit with things used both by builder and Pars7. I separated
  18.                the builder from the parser so the builder can be overlaid.)
  19. Realtype.pas  (Small unit defining the type "float". Change if you want to
  20.                compile in N- mode.)
  21. P7demo.pas   (Demonstrates capabilities and limitations of parsed functions.)
  22. d3FGraf.pas  (Demo, graphing functions of 2 variables.)
  23. Grafpack.pas (Unit with graphics things to do 3-d. Redirection of output
  24.               to the graphics screen is based on the same in Turbo Graphix.)
  25.  
  26. Feel free to distribute this, as long as you keep the original package
  27. intact. The only things I have used to write this are Borland Pascal 7.0
  28. and TurboGraphix, so I guess it's all mine.
  29. The package is an updated version of a previous one, uploaded under the
  30. name pars6.
  31. Changes: Adjusted so usable for DOS protected mode.
  32.          A little more forgiving in syntax (extra ()).
  33.          Builds faster, runs slightly faster.
  34.          Supports use of 5 parameters that can be changed
  35.          without the function to have to be built again.
  36.          Has a really working complete destructor.
  37.          Supports some more functions, mainly to make
  38.          it easier to implement complex functions.
  39. All things compile and run in real and protected mode, that is, unless
  40. your application digs up another one of my sloppy pointers. It should
  41. not be happening, if it does, let me know, please.
  42.  
  43. ******************  What is does: ****************************************
  44.  
  45. Suppose you want to display the graph of a function, say f(x) = sin(x)/x.
  46. So you write a program with "function f(x:real):real;" etc. and some
  47. graphics to display it. If you want to display the next function you
  48. change the string under "function...", recompile, and there you are.
  49. That's not very handy, especially if you maybe want to give this
  50. routine to a user that does (and should) not care about programming, like
  51. a student in a math class. Professional packages like Eureka, Mathematica,
  52. Mathcad etc. let you enter a function string at run time and then display
  53. the graph.
  54. You can use Pars7 to write applications that do similar things. You can
  55. incorporate functions into your program whose definition is not known at
  56. compile time and that only get built up at run time when initialized by
  57. a string entered by the user. Of course, it's not a good idea to parse
  58. the string each time it's supposed to get evaluated, so this is done only
  59. once in the beginning. Pars7 translates a string into the appropriate
  60. sequence of operations in memory, and only this tree is being run through
  61. each time the program calls the corresponding function.
  62.  
  63. The resulting function takes more time for evaluation than if it had been
  64. compiled. The exact amount seems to differ a lot with the hardware.
  65. On my crummy 286 at home it takes a little more than twice the time, on
  66. my 486 at work it only takes about 30% more. Still, this is faster than
  67. any parser I have seen in the public domain and been able to try.
  68.  
  69. I've written this tool for use in math programs that have a handy user
  70. interface, so the students can concentrate on the exploring side and
  71. don't have to spend weeks to learn a command language. I've looked
  72. around on CompuServe whether anything like this parser is available, but
  73. it does not seem so. This is why I upload the program so maybe others
  74. with similar applications in mind can use it.
  75.  
  76.  
  77. ________________________________________________________________________
  78. | I'm happy about any comments, suggestions, bug reports etc. that you |
  79. | might have. Especially, if you professionals could tell me, how to   |
  80. |_get this thing faster._______________________________________________|
  81.  
  82.  
  83. I'm now just giving away the source code, what the hack, with all those
  84. TPU-TPP-types around it's a little cumbersome otherwise.
  85.  
  86. ************************* Syntax of Strings: ********************************
  87. Basicly, the syntax is the same as in Pascal.
  88.  
  89. Function strings denoting real valued functions of up to three real
  90. variables are supported, the variables have to be
  91.                      __________________
  92.                     |                  |
  93.                     |  'x' 'y' 't'     |
  94.                     |__________________|
  95.  
  96. (That's because I've written it for use with an ODE-package.)
  97.  
  98. Examples: 'exp(x*(y-1)) - t*ln(1+x^2)'  'arctan(x+y)'  'sin(x)/x'.
  99.  
  100. All names of real valued functions in the system unit can be used.
  101. You can incorporate up to 5 parameters if you call them 'A','B','C',
  102. 'D','E'. Use setparams of OParse to assign values to them.
  103. Differences:
  104. 1) Use only lower case (except for parameters and the number 'Pi'):
  105.     'Sin(x)*exP(x)' causes an error, 'sin(A*x)*exp(x)' is good, even
  106.     '(((sin( A*x )))) * exp ( x )'. It needs the '*'.
  107.  
  108. 2) Powers can be denoted by '^':
  109.     '(x^2 + y^2)^(-0.3)'   'y^(x^2)'
  110.    If in doubt, rather use those extra brackets.
  111.  
  112. 3) Some more functions are supported:
  113.    a) min(x,y) :  the minimum of x and y.
  114.    b) max(x,y) :  the maximum of x and y.
  115.    c) heav(x)  :  the heaviside jump function:
  116.                   heav(x) is =1 for x>0 and =0 for x<=0.
  117.    d) cosh(x),sinh(x): hyperbolic functions.
  118.    e) arg(x,y):   angle of (x,y) with the x-axis (between -pi
  119.                   and pi).
  120.    f) r(x,y):     distance of (x,y) from (0,0).
  121. There's also 2 kinds of random functions built in, whose use is a little
  122. hard to explain. rndm(A,B) creates N(A,B)-distributed white noise, e.g..
  123. Maybe you can figure out things by yourself.
  124.  
  125.  ********************* How to use Pars7: ***********************************
  126.  
  127.  Here's the interface of the unit:
  128.  ___________________________________________________________________________
  129. unit pars7;
  130. {$O+,F+}
  131. interface
  132.  
  133. uses builder,pars7glb,realtype;
  134.  
  135. type
  136.  
  137. PParse = ^OParse;
  138.  
  139. OParse = object
  140.   fstring:string;
  141.   px,py,pt,pa,pb,pc,pd,pe: rpointer;
  142.   numop:integer;
  143.   fop:operationpointer;
  144.   constructor init(s:string; showprogress: boolean; var error:boolean);
  145.   procedure setparams(a,b,c,d,e:float);
  146.   procedure f(x,y,t:float;var r:float);
  147.   destructor done;
  148. end;
  149. ____________________________________________________________________________
  150.  
  151. Description of OParse:
  152.  
  153.   fstring:  the string that defines the function to be parsed.
  154.   px,py,pt: pointers to the fields in memory where the values
  155.             of x,y,t go when the function gets evaluated.
  156.   pa,pb,pc,pd,pe: same for the locations where the parameter values
  157.             go.
  158.   fop:      pointer to the first operation to be carried out when the
  159.             function is called.
  160.   px, py, pt, fop,... get to point to the right things in memory
  161.   after OParse.init has been called. fop^.next then points to the
  162.   next operation and so on.
  163.   init:     allocates memory on the heap for px,py,pt,... and builds
  164.             up a sequence of operations starting with fop^ to evaluate
  165.             the expression given by s. If s is not a valid string, error
  166.             is true and the function OParse.f cannot be used.
  167.             If showprogress is true then the builder puts dots on the
  168.             screen to show that it's doing things.
  169.   f:        This is the function the application program can call after
  170.             a successful call to init in order to evaluate fstring.
  171.             Actually, it's a procedure rather than a function in
  172.             order to speed things up a little.
  173.   setparams:  procedure that assigns the values a,b,c,d,e to the
  174.               parameters. Call each time you want to change parameter
  175.               values.
  176.               (Actually you can fake a function of 8 variables this
  177.                way)
  178.   done:     Destructs everything that init has thrown on the heap.
  179.  
  180.  
  181.  
  182.  
  183. Here is the implementation of OParse.f:
  184.  
  185. type rpointer=^float;        {In Pars7glb}
  186.      onestep=procedure;
  187.      operationpointer=^operation;
  188.      operation=record
  189.              arg1,arg2:rpointer;
  190.              dest:rpointer;
  191.              next:operationpointer;
  192.              op:onestep;
  193.              opnum:word;
  194.             end;
  195.  
  196. procedure OParse.f(x,y,t:float;var r:float);
  197. begin
  198.     px^:=x; py^:=y; pt^:=t;
  199.     lastop:=fop;
  200.     while lastop^.next<>nil do
  201.     begin
  202.       lastop^.op;
  203.       lastop:=lastop^.next;
  204.     end;
  205.     lastop^.op;
  206.     r:=lastop^.dest;
  207. end;
  208.  
  209. lastop is a "semiglobal" variable of type operationpointer that
  210. gets used by the instances of lastop^.op (funny, but it works).
  211. Actually, I've found out that here "while" is a little faster than
  212. "repeat".
  213.  
  214. Here's an example application program that should explain everything:
  215.  
  216. program example;
  217. {$M 35000,0,655360}    {It's safe to increase the stack size, the builder}
  218. uses pars7,realtype;   {uses a bit of it, though not for these examples}
  219. var Myfunc:PParse;
  220.     error:boolean;
  221. begin
  222.   Myfunc:=New(PParse,init('x*y*t-A',true,error));
  223.   if not error then
  224.   begin
  225.     Myfunc^.setparams(1,0,0,0,0);
  226.     Myfunc^.f(2,1,3,r);
  227.     writeln(r:5:2);
  228.     dispose(Myfunc,done);{Always dispose of a function you don't need}
  229.                          {anymore. Never dispose of   }
  230.                          {a function whose init failed.}
  231.   end;
  232.   Myfunc:=New(PParse,init('x*exp(x-1)',true,error));
  233.   if not error then
  234.   begin
  235.     Myfunc^.f(1,0,0,r);  {f is only a function of 1 variable really
  236.                                     but has to be called with 3 arguments.}
  237.     writeln(r:5:2);
  238.     dispose(Myfunc,done);
  239.   end;
  240. end.
  241.  
  242.  
  243. Output:
  244.  
  245. .......5.00
  246. ........1.00
  247.  
  248. (init puts the dots on the screen to indicate its progress when
  249. showprogress is true.)
  250.  
  251. Easy, ain't it?
  252.